The world consists of one area, which is regular in shape and consists of a number of cells. Each cell has a type of terrain and a number of optional data values. Each kind of per-cell data will be called a layer of the area.
Form: world [ circumference ] properties...
This form defines the properties of the world as a whole.
Form: area [ width [ height ] ] [ restriction ] properties...
This form defines the playing area of the world. The restriction identifies how to get data for this area from subsequent forms that are based on larger areas.
WorldProperty: circumference dist
This property is the distance in cells around the entire world (as a sphere).
Default is 360.
WorldProperty: axial-tilt n
This property defines the extremes of seasonal changes.
AreaRestriction: restrict w h x y
This is a special subform that specifies that subsequent layers in an area of size w x h will be offset by x,y and then read into the actual area. (This is useful for setting up a game that needs only a subset of a full map.)
Note that an area restriction is not a property, and must always appear before any properties in an area form.
AreaProperty: width n
These properties are the width and height of the world,
as measured in cells.
Allowable values range from 3x3
up to 32767x32767, which is one billion cells!
If only one of these is given, then the other defaults to the same value.
If neither has been given, then they default to 60 and 30,
respectively.
In the case of a cylinder, the world wraps around in the x direction, and the width is the diameter of the cylinder, while the height is just the height in the usual sense. A hexagon world is flat on the top and bottom; its width is measured across the middle height, which is the largest span, and height is the same as for cylinders. Here are some crude pictures, first of an 8x6 cylinder:
# # # # # # # # : : + + : : : : : : : + ^ : : : : : : : : : : : : : : : ^ : : : # # # # # # # #
This world is an 8x7 hexagon:
# # # # # # : + + : # # : : + ^ : # # : : + ^ : : # # : : : : : # # : : ^ : # # # # # #
There are two kinds of properties that an area may have: scalar values such as latitude, and layer values such as terrain and elevation.
AreaProperty: latitude n
This property is the offset, in cells, from the equator of the middle of the area (height / 2).
AreaProperty: longitude n
This property is the offset, in cells, from the "Greenwich Meridian" of the world.
AreaProperty: projection n
This property defines the mapping from the world to the area. The default
value of 0 maps lat,long positions to x,y coordinates directly
(with the effect of stretching high latitude terrain horizontally).
A value of 1 bends x coordinates in towards the middle of the
area, proportionally to the latitude (meridians will be curved in a
familiar fashion).
Layers constitute the bulk of data about an area of the world.
Each layer assigns a value to each cell in the area;
examples include cell terrain, temperatures, elevations, and so forth.
Since there may be many cells in a layer with the same values,
each layer uses a common run-length encoding scheme.
In this scheme, each horizontal band of cells
is a separate text string, and the contents of the string encode
individual numeric values, one for each cell.
The encoding uses the characters a..~ and :..[
for 0 through 63,
and decimal digits followed by commas (or the end of the string)
for all other numbers.
An optional - is allowed, and indicates a negative value.
Runs of constant value are prefixed with their length, in decimal.
The character * separates run lengths from values expressed
as digits.
Thus, the string
"40adaa100,2*-99"
represents 46 values in all: 40 zeroes, a three, 2 more zeros, a 100, and two -99s. Although this format is quite unreadable, it has the advantages of compactness and portability; the expectation is that most layer editing will be done on-line. Note that the run encoding is entirely optional.
The following subforms at the beginning of layer data have special effects:
LayerSubform: constant n
This subform causes every value in the layer to be set to n.
LayerSubform: subarea x y w h
This subform indicates that the layer data should be positioned at the given rectangle in the layer.
LayerSubform: xform mul add
This subform has the effect of first multiplying the raw value by mul, then adding add and storing the result into the layer.
LayerSubform: by-bits
LayerSubform: by-char str
This subform specifies that the characters in str give the encodings of values in the layer. The first character in str encodes 0, the second encodes 1, and so forth.
LayerSubform: by-name name-list
[what is the syntax of name-list exactly?]
This subform is for generic worlds that are useful across multiple game designs.
It has the syntax ((sym1 n1) (sym2 n2) ...), where symi is
either a symbol or number that is the real value in the layer, and ni
is the value used in the layer's encoding.
For example, in the terrain layer,
this allows for the matching of terrain types by name,
so that if, say,
the "sea" terrain type was type #0 in one game and type #4 in another,
the world would have sea in all the same places after it was read in.
In practice, only a few worlds are this general.
If a value appears in the layer's data that is not listed,
that value will simply go into the layer verbatim.
AreaProperty: terrain layer-data...
This property is the actual layer of terrain types for cells.
AreaProperty: aux-terrain terrain-type layer-data...
This property fills in values for borders, connections, and coatings. For border and connection terrain, the value is a six-bit number (0..63), with a bit turned on in each direction that there is a border or connection. For coating types, the value is the depth of the coating.
AreaProperty: features feature-list layer-data...
This property specifies the nature and location of all geographical features.
The feature-list is a list of lists, where each sublist has the form
([id] typename name)
where id is the numerical id referenced in the layer data
(defaults to feature's position in the feature-list),
typename is a symbol or string giving the general type of feature
(such as continent),
and name is the name of the feature
(such as "Asia").
If the name includes the string "%T", then the feature's type will
be substituted at that position; so for instance the name "%T of Mexico"
with a type gulf results in a displayed name "Gulf of Mexico".
AreaProperty: material material-type layer-data...
This property declares the quantity of the given material-type in each cell of the area.
AreaProperty: people-sides layer-data...
This property says which side the people of each cell are on.
A side-encoding of exact assigns 0 to independence (no side),
1 to the first side, and so forth; otherwise, the encoding is a list
of side names/ids and numbers.
AreaProperty: control-sides layer-data...
This property says which side controls each cell.
The encoding is the same as for people-sides.
The unit of elevation is arbitrary, with its relation to cells defined by the area's cell width.
AreaProperty: elevations layer-data...
This property is the world elevation data itself. If any elevation falls outside the min/max elevation range for the terrain type of the cell, then it will be truncated appropriately.
AreaProperty: cell-width elev
This property is the distance across a single cell,
expressed as units of elevation. Defaults to 1.
Each type of terrain has a temperature range in which it may be found. Any calculation that would fall outside this range will be clipped.
The temperature can be set to have a given value at a given elevation. All air temperatures will be interpolated appropriately.
GlobalVariable: temperature-floor n
This variable is the lowest possible temperature.
GlobalVariable: temperature-floor-elevation n
This variable is the elevation at which the temperature is always at
temperature-floor.
AreaProperty: temperatures layer-data...
This property contains the temperature data itself. If any temperature falls outside the min/max temperature range, then it will be truncated appropriately.
Winds are defined as having a nonnegative force and a direction.
AreaProperty: winds layer-data...
This property contains the force and direction of the prevailing winds in each cell.
Cloud cover is defined as a layer over the terrain, with a bottom and top and density for each cell.
AreaProperty: clouds layer-data...
This property is the degree of cloud cover over each cell.
A value of 0 corresponds to clear skies.
AreaProperty: cloud-bottoms layer-data...
This property is the altitude above the ground of the bottoms of the clouds.
AreaProperty: cloud-heights layer-data...
This property is the vertical thickness of the cloud cover in each cell.